CONTENTS
VOSS FileManager++ 1.5

C++ File Manager(TM) Extension Support Library

c. 1994 Van de Vate Object-Oriented Software Solutions - All rights reserved.

Overview

License & Warranty

Class API

Registration

Installation

Example1  (without VFMXMenuItem)

Example2  (with VFMXMenuItem)

Contacting the Author

Microsoft, Windows, and File Manager  are registered trademarks of Mircrosoft Corporation.

CompuServe  is a registered trademark of CompuServe, Inc.


Overview

FileManager++ provides an exported C++ class API for defining extensions or "add-ons" to the

File Manager(TM) application that is delivered as a standard part of Microsoft(R) Windows(TM). An extension is contained in a Windows DLL.  This DLL is loaded when the File Manager starts and may add a pull down menu of commands to the File Manager menu bar.

FileManager++ extensions are notified via a typical callback routine of various events including:

 An extension pull-down menu has been selected and needs to be initialized.

 The currently selected file has changed.

 The user has refreshed the File Manager window.

 An extension pull-down menu item has been selected.

The FileManager++ extension API also provides access to the various pieces of information including:

 Information regarding the current drive and directory.

 Information regarding the currently selected file(s).

 The File Manager window handle.

The FileManager++ extension API also provides a means of directing the Windows File Manager to perform various tasks including :

 Refresh the File Manager window.

 Reload the extension DLL(s).

The Win32 File Manager extension API adds various capabilities including the following :

 The ability to add tool bar bitmaps to the File Manager.

 The ability to provide context sensitive help for extension menu items.

 The ability to determine the type of File Manager window currently in focus.

These Win32 features are not supported by FileManager++ 1.0.


ClassAPI
FileManager++ Class API

The FileManager++ class API is made up of five C++ classes exported from VOSSFMGR.DLL.  Central to this class API is the class VFileManagerExtension.  This class is the class that a developer derives an extension DLL from.  The interface of VFileManagerExtension provides access to VFMXDriveInfo, VFMXFileInfo,  VFMXDate, and VFMXTime.  The VFMXDriveInfo class encapsulates information regarding the current file and directory.  The VFMXFileInfo class encapsulates information regarding the currently selected file.   VFMXDate and VFMXTime encapsulate date and time values respectively.

VFMXMenuItem has been added to further encapsulate menu processing.  This class allows all menu item behaviors to be defined in individual virtual callback methods thus eliminating the need for the large ugly switch-case statement.

NOTICE:  API functions that use enumerated types will NOT link with BC++ 3.1 due to changes in the name mangeling definitions.  See VFMXFileInfo


VFileManagerExtension

The VFileManagerExtension class is the base class for all derived File Manager extensions.  The class interface consists of the following methods which can be divided into four different groups.

Methods to Obtain Information  from the File Manager:

      operator[]()

      Delta()

      DriveInfo()

      FileManager()

      FileSelection()

      SelectionCount()

      WindowTypeInFocus()

Commands to the File Manager :

      Refresh()

      Reload()

Notifications and Requests Received from the File Manager :

      ExtensionMenu()

      InitMenu()

      ItemHelpString()

      MenuCommand()

      MenuName()

      SelectionChange()

      UserRefresh()

      Process()

Miscellaneous Methods :

      VFileManagerExtension()

      ~VFileManagerExtension()

      Win32Version()

      operator VFileManagerExtensionInt&()

      UserRegistration()


Delta

Method:

Delta

Class :

VFileManagerExtension

Arguments:

void

Description :

The items on the menu resource defined by a File Manager extension must have identifiers ranging from 1 to 99.   However, the File Manager will add an offset or "delta" to each menu identifier in a given extension to form the actual menu item that is placed on the File Manager menu bar.  The purspose of this delta is to ensure that menu identifiers are unique across extensions.  This method returns this delta value.

Return:

WORD


DriveInfo

Method:

DriveInfo

Class :

VFileManagerExtension

Arguments:

void

Description :

This method returns information regarding the currently selected drive and directory.  This information is

encapsulated in the class VFMXDriveInfo.

Return:

VFMXDriveInfo&


FileManager

Method:

FileManager

Class :

VFileManagerExtension

Arguments:

void

Description :

This method returns the window handle of the File Manager window.

Return:

HWND


FileSelection

Method:

FileSelection

Class :

VFileManagerExtension

Arguments:

int iSelectionIdx

Description :

This method returns information regarding a currently selected file.  The iSelectionIdx argument indicates the 0 based index for requesting information on one of multiply selected files.  The method returns the information encapsulated in VFMXFileInfo.

Return:

VFMXFileInfo&

See Also:

SelectionCount


operator[]

Method:

operator[]

Class :

VFileManagerExtension

Arguments:

int iSelectionIdx

Description :

This method defines an overload of the array indexing operator to return information regarding a currently selected file.  The iSelectionIdx argument indicates the 0 based index for requesting information on one of multiply selected files.  The method returns the information encapsulated in VFMXFileInfo.

Return:

VFMXFileInfo&

See Also:

FileSelection

SelectionCount


SelectionCount

Method:

SelectionCount

Class :

VFileManagerExtension

Arguments:

void

Description :

This method returns the number of currently selected files in the File Manager window.

Return:

WORD


WindowTypeInFocus
WindowTypeInFocus  (WIN32)(BC4.0)

Method:

WindowTypeInFocus

Class :

VFileManagerExtension

Arguments:

void

Description :

This method returns an enumerated value indicating what type of File Manager window

is currently in focus. The value may be one of the following values:  (1) Directory Tree Window,

(2) File Tree Window, (3) Drive Selection Window, or (4) Search Results Window.

Return:

VFMWindowTypeET


UserRegistration

Method:

UserRegistration

Class :

VFileManagerExtension

Arguments:

void

Description :

FileManager++ calls  this virtual method to ensure that the product has been properly registered.  If NULL or an invalid string is returned,  FileManager++ will display the "nag" message box whenever a derived extension DLL is loaded by the File Manager.

Return:

const char *

See Registration and License & Warranty for more details regarding user registration.


Refresh

Method:

Refresh

Class :

VFileManagerExtension

Arguments:

BOOL bAllWindows

Description :

This method causes FileManager++ to either instruct the File Manager to refresh the contents of its active window (bAllWindows=FALSE) or all of its windows (bAllWindows=TRUE).  The default for bAllWindows is FALSE.

Return:

void


Reload

Method:

Reload

Class :

VFileManagerExtension

Arguments:

void

Description :

This method causes FileManager++ to  instruct the File Manager to reload all of the extension DLLs listed in the addons section of WINFILE.INI.

Return:

void


ExtensionMenu

Method:

ExtensionMenu

Class :

VFileManagerExtension

Arguments:

void

Description :

FileManager++ calls this pure virtual method whenever the File Manager requests the menu resource that is to be inserted on the File Manager menu bar for the derived extension.  A derived extension must override this method to return the handle obtained by calling LoadMenu() or from OWL2.0's TMenu class.  This method is called at load time.

Return:

HMENU

If this method returns NULL or 0,  the message "No Menu Resource Specified" will be displayed and the extension DLL will not be loaded.


InitMenu

Method:

InitMenu

Class :

VFileManagerExtension

Arguments:

HMENU hPopupMenu

int iMenuDelta

Description :

FileManager++ calls this virtual method whenever the user selects the extension's menu on  File Manager menu bar. A derived extension can override this method to initialize the items on the menu (hPopupMenu).  Note that the item numbers on the menu are those specified in the extension's menu resource plus an offset (iMenuDelta).  Submenus must be initialized at the same time as the main popup.

Return:

void

Note that an alternative to overriding this method and encoding a large ugly  switch-case  statement is to use the VFMXMenuItem class to encapsulate each menu item's behavior


ItemHelpString
ItemHelpString  (WIN32)

Method:

ItemHelpString

Class :

VFileManagerExtension

Arguments:

WORD wItemNumber

Description :

This method is only functional in WIN32.   FileManager++ calls this virtual method whenever the File Manager requests a help string for a particular menu item.  The item number specified is the menu item identifier in the extension's menu resource.  That is,  the delta value has already been removed.  Derived extensions should override this method to return a help string corresponding to the menu item specified.

Return:

const char *

Note that an alternative to overriding this method and encoding a large ugly  switch-case  statement is to use the VFMXMenuItem class to encapsulate each menu item's behavior


MenuCommand

Method:

MenuCommand

Class :

VFileManagerExtension

Arguments:

WORD wItemNumber

BOOL  bHelpWanted     (for WIN32 use only)

Description :

FileManager++ calls this virtual method whenever the File Manager indicates that the user has selected a command from the extension's menu.  The menu item specified by (wItemNumber) is the actual resource value.  The menu delta has already been removed.  A derived extension should override this method to respond to user selections.

Return:

void

Note that an alternative to overriding this method and encoding a large ugly  switch-case  statement is to use the VFMXMenuItem class to encapsulate each menu item's behavior


MenuName

Method:

MenuName

Class :

VFileManagerExtension

Arguments:

void

Description :

FileManager++ calls this pure virtual method when the File Manager needs to know what to name the derived extension's menu.  The string returned by this method will be used as the name of the extension's pull down menu on the File Manager's menu bar.

Return:

const char *

Note that if this method returns NULL or 0, the message  "No Menu Title Specified" will be displayed and the extension DLL will not be loaded.


SelectionChange

Method:

SelectionChange

Class :

VFileManagerExtension

Arguments:

void

Description :

FileManager++ calls this virtual method when the user changes the selected file or directory.  Derived extensions may override this method to process this event.

Return:

void


UserRefresh

Method:

UserRefresh

Class :

VFileManagerExtension

Arguments:

void

Description :

FileManager++ calls this virtual method when the user refreshes or updates the current window in the File Manager.  Derived extensions may override this method to process this event.

Return:

void


Process

Method:

Process

Class :

VFileManagerExtension

Arguments:

WORD       wMsg

LPARAM   lParam

Description :

This virtual method is called for every message the extension DLL receives from the File Manager. The method may be overriden,  but it is recommended that the more specific virtual message handlers defined in VFileManagerExtension be overriden instead.

Return:

void


VFileManagerExtension

Method:

VFileManagerExtension

Class :

VFileManagerExtension

Arguments:

void

Description :

This method is the class constructor.  It is called when the derived extension class is allocated.  The constructor initializes the class internals.

Return:

n/a


~VFileManagerExtension

Method:

~VFileManagerExtension

Class :

VFileManagerExtension

Arguments:

void

Description :

This method is the class destructor.  It is called when the extension DLL is unloaded by the File Manager.  The destructor destroys the class internals.

Return:

n/a


Win32Version

Method:

Win32Version     (protected)

Class :

VFileManagerExtension

Arguments:

void

Description :

This method returns TRUE if the version of the FileManager++ DLL was compiled for WIN32.  The

method returns FALSE otherwise.

Return:

BOOL


operator VFileManagerExtensionInt&
operator VFileManagerExtensionInt&()

Method:

operator VFileManagerExtensionInt&()

Class :

VFileManagerExtension

Arguments:

void

Description :

This method defines a cast operator which returns a reference to the class internals.  This method is for internal use only as the definition of VFileManagerExtensionInt is not visible without the complete source code.

Return:

VFileManagerExtensionInt&


VFMXDriveInfo

The VFMXDriveInfo class encapsulates information regarding the currently selected drive and directory in the File Manager.  The clss interface consists of the following methods:

      CurrentDirectory()

      FreeSpace()

      operator VFMXDriveInfoInt&()

      SharePoint()

      TotalSpace()

      VFMXDriveInfo()

      ~VFMXDriveInfo()

      VolumeLabel()

This class API is accessible by calling the DriveInfo method of VFileManagerExtension


CurrentDirectory

Method:

CurrentDirectory

Class :

VFMXDriveInfo

Arguments:

void

Description :

This method returns a string containing the complete path, including the drive specified,  to the directory currently selected in the File Manager.

Return:

const char *


FreeSpace

Method:

FreeSpace

Class :

VFMXDriveInfo

Arguments:

void

Description :

This method returns the bytes free space available on the drive (device) currently  selected in the File Manager.

Also see TotalSpace()

Return:

DWORD


operator VFMXDriveInfoInt
operator VFMXDriveInfoInt&

Method:

operator VFMXDriveInfoInt&

Class :

VFMXDriveInfo

Arguments:

void

Description :

This method defines a cast operator which returns a reference to the class internals.  This method is for internal use only as the definition for VFMXDriveInfoInt is not visible without the complete source code.

Return:

VFMXDriveInfoInt&


SharePoint

Method:

SharePoint

Class :

VFMXDriveInfo

Arguments:

void

Description :

If the currently selected drive (device) in the File Manager is a network device,  this method returns a string containing the device name.

Return:

const char *


TotalSpace

Method:

TotalSpace

Class :

VFMXDriveInfo

Arguments:

void

Description :

This method returns the bytes total space on the drive (device) currently  selected in the File Manager.

Also see FreeSpace()

Return:

DWORD


VFMXDriveInfo

Method:

VFMXDriveInfo     (private)

Class :

VFMXDriveInfo

Arguments:

void

Description :

This method is the class constructor.  The constructor initializes the class internals.

Return:

n/a


~VFMXDriveInfo

Method:

~VFMXDriveInfo     (private)

Class :

VFMXDriveInfo

Arguments:

void

Description :

This method is the class destructor.  The destructor destroys the class internals.

Return:

n/a


VolumeLabel

Method:

VolumeLabel

Class :

VFMXDriveInfo

Arguments:

void

Description :

This method returns a string containing the volume label of the drive (device) currently selected in the File Manager.

Return:

const char *


VFMXFileInfo

The VFMXFileInfo class encapsulates information regarding the currently selected file in the File Manager.  The clss interface consists of the following methods divided in to three groups:

The following methods provide access to miscellaneous information about the selected file:

      Date()

      Name()

      Size()

      Time()

The following methods provide access to the DOS file attributes of the selected file:  These methods will not link with BC++ 3.1 due to name mangeling changes with enumerated types.

      ReadOnly()

      Hidden()

      System()

      VolumeLabel()

      Directory()

      Archive()

      Normal()

The following methos are miscellaneous class methods:

      VFMXFileInfo()

       ~VFMXFileInfo()

      operator VFMXFileInfoInt&();

This class API is accessible by calling the FileSelection() method of VFileManagerExtension


VFMXAttribState

VFMXAttribState is an enumerate type defined for VFMXFileInfo which has the values test, set, and clear.  This data type is used with the DOS file attribute access methods of  VFMXFileInfo to indicate what is to be done with regard to the encapsulated attribute.  When test is specified,  these methods simple return non-zero if the corresponding attribute is set.  If clear, is specified,  these methods clear the specified attribute and return the resulting state of the attribute.  If set, is specified,  these methods set the specified attribute and return the resulting state of the attribute.  If either the set or clear cases fail,  the resulting state of the attribute will be opposite of what was expected.


Date

Method:

Date

Class :

VFMXFileInfo

Arguments:

void

Description :

This method returns an encapsulation of the DOS file date of the file currently selected in the File Manager.

Return:

const VFMXDate&


Time

Method:

Time

Class :

VFMXFileInfo

Arguments:

void

Description :

This method returns an encapsulation of the DOS file time of the file currently selected in the File Manager.

Return:

const VFMXTime&


Size

Method:

Size

Class :

VFMXFileInfo

Arguments:

void

Description :

This method returns the size in bytes of the file currently selected in the File Manager.

Return:

DWORD


Name

Method:

Name

Class :

VFMXFileInfo

Arguments:

void

Description :

This method returns a string containing the fully qualified path to the currently selected file in the File Manager.

Return:

const char *


ReadOnly
ReadOnly (BC4.0)

Method:

ReadOnly

Class :

VFMXFileInfo

Arguments:

VFMXAttribState    etState    (default is test)

Description :

This method modifies the read-only file attribute of the file currenty selected in the File Manager based on the value specified for (etState).  See VFMXAttribState for details.  The return value is TRUE if the specified attribute is set after the operation or FALSE if the attribute has been cleared.

Return:

BOOL


Hidden
Hidden (BC4.0)

Method:

Hidden

Class :

VFMXFileInfo

Arguments:

VFMXAttribState    etState    (default is test)

Description :

This method modifies the hidden file attribute of the file currenty selected in the File Manager based on the value specified for (etState).  See VFMXAttribState for details.  The return value is TRUE if the specified attribute is set after the operation or FALSE if the attribute has been cleared.

Return:

BOOL


System
System  (BC4.0)

Method:

System

Class :

VFMXFileInfo

Arguments:

VFMXAttribState    etState    (default is test)

Description :

This method modifies the system file attribute of the file currenty selected in the File Manager based on the value specified for (etState).  See VFMXAttribState for details.  The return value is TRUE if the specified attribute is set after the operation or FALSE if the attribute has been cleared.

Return:

BOOL


VolumeLabel
VolumeLabel  (BC4.0)

Method:

VolumeLabel

Class :

VFMXFileInfo

Arguments:

VFMXAttribState    etState    (default is test)

Description :

This method modifies the volume label file attribute of the file currenty selected in the File Manager based on the value specified for (etState).  See VFMXAttribState for details.  The return value is TRUE if the specified attribute is set after the operation or FALSE if the attribute has been cleared.

Return:

BOOL


Directory
Directory  (BC4.0)

Method:

Directory

Class :

VFMXFileInfo

Arguments:

VFMXAttribState    etState    (default is test)

Description :

This method modifies the sub-directory file attribute of the file currenty selected in the File Manager based on the value specified for (etState).  See VFMXAttribState for details.  The return value is TRUE if the specified attribute is set after the operation or FALSE if the attribute has been cleared.

Return:

BOOL


Archive
Archive  (BC4.0)

Method:

Archive

Class :

VFMXFileInfo

Arguments:

VFMXAttribState    etState    (default is test)

Description :

This method modifies the archive file attribute of the file currenty selected in the File Manager based on the value specified for (etState).  See VFMXAttribState for details.  The return value is TRUE if the specified attribute is set after the operation or FALSE if the attribute has been cleared.

Return:

BOOL


Normal
Normal  (BC4.0)

Method:

Normal

Class :

VFMXFileInfo

Arguments:

VFMXAttribState    etState    (default is test)

Description :

This method modifies the normal file attribute of the file currenty selected in the File Manager based on the value specified for (etState).  See VFMXAttribState for details.  The return value is TRUE if the specified attribute is set after the operation or FALSE if the attribute has been cleared.

Return:

BOOL


VFMXFileInfo

Method:

VFMXFileInfo      (private)

Class :

VFMXFileInfo

Arguments:

void

Description :

This method is the class constructor.  The constructor initializes the class internals.

Return:

n/a


~VFMXFileInfo

Method:

~VFMXFileInfo      (private)

Class :

VFMXFileInfo

Arguments:

void

Description :

This method is the class destructor.  The destructor destroys the class internals.

Return:

n/a


operator VFMXFileInfoInt&

Method:

operator VFMXFileInfoInt&()

Class :

VFMXFileInfo

Arguments:

void

Description :

This method defines a cast operator which returns a reference to the class internals.  This method is for internal use only as the definition of VFMXFileInfoInt is not visible without the complete source code.

Return:

VFMXFileInfoInt&


VFMXDate

The VFMXDate class encapsulates the  DOS file date of  the currently selected file in the File Manager.  The class interface consists of the following methods :

     Day()          - This method returns the day of the month 1..28,30, or 31.

     Month()      - This method returns the month 1..12

     Year()        -  This method returns the year 1980...

The following methods are the class constructor and destructor.

     VFMXDate()                                   - default constructor.

     VFMXDate(UINT wFileDate)         - constructor to initialize with dos file date.

This class API is accessible by calling the  Date method of VFMXFileInfo


VFMXTime

The VFMXTime class encapsulates the  DOS file time of  the currently selected file in the File Manager.  The class interface consists of the following methods :

      Hour()           - This method returns the hour 0..23

      Minute()        - This method returns the minute 0..59

      Second()       - This method returns the seconds 0..59

The following methods are the class constructor and destructor.

      VFMXTime()                               - default constructor.

      VFMXTime(UINT wFileTime)    - constructor to initialize with dos file time.

This class API is accessible by calling the  Time method  of  VFMXFileInfo


Registration

FileManager++ is not freeware.  A considerable effort went in to preparing the DLL and this on-line help file.

You are allowed 30 days to use the library free of charge in order to  evaluate its effectiveness.

After which time, you are required to register FileManager++.  Upon registration, you will be sent,

via CompuServe mail, a user registration string good for all versions and upgrades of FileManager++.

Registration of this program can be accomplished via the SWREG forum on CompuServe.  The registration number is 3282.  The registration fee is:

           $30.00 per developer

In return, the author will provide, via CompuServe mail, a user registration string good for all versions and upgrades of FileManager++.   Several enhancements to this WIN16 version as well as a potential WIN32 version are anticipated  given that a reasonable amount of interest in the product is demonstrated.  Complete source code is available for an additional fee upon request.

See License & Warranty


License & Warranty

License

Upon registration of the product,  the registered user may use all components of FileManager++ "like a book".  By saying "like a book",  the author means,  for example,  that this software may be used by any number of people,  and may be freely moved from one computer to another,  so long as there is no possibility of it being used by more than one person at a time.  Each additional simultaneous user requires a separate product registration.

Upon registration of the product,  the registered organization is free to redistribute the FileManager++ DLL as part of any product that uses the DLL.  No part of the product's source code or on-line help may be redistributed.

Limited Warranty

This product is delivered as is.  The entire and exclusive liability and remedy for breach of this limited warranty shall be limited to replacement of defective media or documentation and shall not include or extend to any claim for or right to recover any other damages, including but not limited to, loss of profit,  data, or use of the software or special, incidental or consequential damages or other similar claims.

THE AUTHOR SPECIFICALLY DISCLAIMS ALL OTHER WARRANTIES,  REPRESENTATIONS, OR CONDITIONS, EXPRESS OR IMPLIED,  INCLUDING BUT NOT LIMITED TO,  ANY IMPLIED WARRANTY OR CONDITION OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.  ALL OTHER IMPLIED TERMS ARE EXCLUDED.


Installation

To install FileManager++ take the following steps:

1. Unzip the VOSSFMGR.ZIP.

2. Place VOSSFMGR.HPP anywhere in your compiler's include path.

3. Place VOSSFMGR.DLL anywhere in your DOS path.

4. Place VOSSFMGR.LIB   whereever your import libraries are kept.

5. Setup a new DLL project with LibMain(), etc.

6. Include VOSSFMGR.HPP in your source file.

7. Add VOSSFMGR.LIB to your project.

8. Be sure STRICT is defined for your extension project.

Note that if you plan to include VOSSFMGR.HPP in more than one source file in your project,

you will need to move the following function body out of your code and in to one of your

source files.  Failure to do so will result in the linker generating symbol redefinition errors.

extern "C"  LONG WINAPI FMExtensionProc(HWND hFileMgr,WORD wMsg, LONG lParam)

{

}

This should be all there is to installing FileManager++.  See the discussion of the  code (Example1 and Example2) to see how to get started defining a derived extension class.


Contacting the Author

Van de Vate Object-Oriented Software Solutions may be reached via CompuServe @ 71055,1001.


VFMXMenuItem

The VFMXMenuItem class encapsulates the behavior of extension menu items.  Derived extensions may derive menu item classes from this class to define such behaviors as

* When is an item enabled, disabled, and/or checked.

* What should be done when the item is selected.

* What is the help string for the item.

The VFMXMenuItem class interface consists of the following methods :

         CheckedBitmap()

         CheckMarkDimensions()

         Execute()

         Extension()

         HelpString()

         IsEnabled()

         IsChecked()

         MenuCommand()

         ShowHelp()

         UncheckedBitmap()

         VFMXMenuItem()

Instances of  this class should be created in the constructor of the derived extension as shown in

Example2


CheckedBitmap

Method:

CheckedBitmap

Class :

VFMXMenuItem

Arguments:

void

Description :

A menu item may have an alternative bitmap that should be displayed when the menu item is in a checked state rather than the standard check mark.   If a derived menu item returns a valid bitmap handle to both this method and UncheckedBitmap,  the FileManager++ will apply the specified bitmaps to the encapsulated menu item.

Return:

HBITMAP

See  documentation on the Windows API function SetMenuItemBitmaps() for more details regarding the bitmap returned

.


Execute

Method:

Execute

Class :

VFMXMenuItem

Arguments:

void

Description :

This method is called when the encapsulated menu item is selected by the user.  Derived menu item classes should override this method to encapulated application behavior associated with the menu item.

Return:

void


Extension

Method:

Extension

Class :

VFMXMenuItem

Arguments:

void

Description :

This method is provided for convience.  The method returns a pointer to the extension class that created the menu item.

Return:

VFileManagerExtension *


HelpString
HelpString  (WIN32)

Method:

HelpString

Class :

VFMXMenuItem

Arguments:

void

Description :

This method is called when the File Manager requests a help string for the encapsulated menu item.  The File Manager only requests such a string in WIN32.

Return:

const char *


IsEnabled

Method:

IsEnabled

Class :

VFMXMenuItem

Arguments:

void

Description :

This method is called to determine if the encapsulated menu item is enabled or not.  If this method returns 0, FileManager++ will gray the menu item.  If the method returns non-zero,  FileManager++ will ungray the menu item.

Return:

int


IsChecked

Method:

IsChecked

Class :

VFMXMenuItem

Arguments:

void

Description :

This method is called to determine if the encapsulated menu item should be checked.  If this method returns 0, FileManager++ will uncheck the menu item.  If the method returns non-zero,  FileManager++ will check the menu item.  See CheckedBitmap() and UncheckedBitmap() for additional information about menu item checking.

Return:

int


MenuCommand

Method:

MenuCommand

Class :

VFMXMenuItem

Arguments:

void

Description :

This method simply returns the menu command of the encapsulated menu item.  The Delta is not included in this value.

Return:

int


ShowHelp
ShowHelp  (WIN32)

Method:

ShowHelp

Class :

VFMXMenuItem

Arguments:

void

Description :

This method is called when the File Manager requests that a WinHelp topic be displayed for the encapsulated menu item.  A derived menu item should execute WinHelp for the appropriate topic.  The File Manager only requests such a string in WIN32.

Return:

void


UncheckedBitmap

Method:

UncheckedBitmap

Class :

VFMXMenuItem

Arguments:

void

Description :

A menu item may have an alternative bitmap that should be displayed when the menu item is in an unchecked state.  If a derived menu item returns a valid bitmap handle to both this method and CheckedBitmap,  the FileManager++ will apply the specified bitmaps to the encapsulated menu item.

Return:

HBITMAP

See  documentation on the Windows API function SetMenuItemBitmaps() for more details regarding the bitmap returned


VFMXMenuItemFunc
VFMXMenuItem

Method:

VFMXMenuItem

Class :

VFMXMenuItem

Arguments:

VFileManagerExtension *    opExtension

int                                        iMenuCommand

Description :

This is the class constructor for the menu item encapsulation.  The first argument is a pointer to the derived extension that is defining the menu item.  The second is the identifier 1..99 of the menu item to be encapsulated by the class instance.

See the Example2 for details on the usage of this constructor.


Example2

Example2 takes advantage of the new class VFMXMenuItem to better process menu item behavior in a more object-oriented fashion than did Example1. Our example class definition looks as follows:

class _export ExampleClass : public VFileManagerExtension

{

   private:

       HMENU hMenu;

   public:

       ExampleClass(void);

       ~ExampleClass(void) {DestroyMenu(hMenu);}

       HMENU    ExtensionMenu(void) {return hMenu;}

       const char *MenuName(void)      {return "Exa&mple";}

       void            SetReadOnly(BOOL bOnOff=TRUE);

};

Note the two inline methods ExtensionMenu() and MenuName().  ExtensionMenu() will return the handle of our extension menu that we will load in the constructor.  MenuName() returns the string that will appear on the File Manager's menu bar for our extension menu.

All extensions must define the body of  AllocateExtension().  This method is called by File Manager++ when the extension DLL is loaded to allocate your derived extension class.

VFileManagerExtension * AllocateExtension(void)

{

   return new ExampleClass();

}

To demonstrate the new capabilities provided by VFMXMenuItem we also define a derived menu item class to encapsulate the behavior of our menu items:

class _export ExampleMenuItem  : public VFMXMenuItem

{

   public:

       ExampleMenuItem(VFileManagerExtension *opExtension,int iMenuCommand)

               : VFMXMenuItem(opExtension,iMenuCommand) {};

       void SetReadOnly(BOOL bOnOff=TRUE);

       virtual int  IsEnabled(void) {return (Extension()->SelectionCount() != 0);}

       virtual void Execute(void)   {SetReadOnly(MenuCommand() == CM_READONLY);}

};

In the body of the constructor for our example class,  we will load a menu resource.  Keep in mind,  that

the items on this menu may only have command values between 1and 99.  In addition, we also create two

instances of ExampleMenuItem to encapsulate the behavior of our two menu items.

ExampleClass::ExampleClass(void) :VFileManagerExtension()

{

   hMenu = LoadMenu(xhLibInstance,MAKEINTRESOURCE(IDM_MENU));

   new ExampleMenuItem(this,CM_READONLY);

   new ExampleMenuItem(this,CM_WRITEABLE);

}

When our menu items are selected FileManager++ will call the Execute method of ExampleMenutItem which we have encoded to call the following method to loop through the selected files and write-protect or unwrite-protect each of the selected files:

void ExampleMenuItem::SetReadOnly(BOOL bOnOff)

{

   int nSelections = Extension()->SelectionCount();

   for (int iSelection=0;iSelection<nSelections;iSelection++)

       {

        VFMXFileInfo& oFileInfo = Extension()->FileSelection(iSelection);

        if (bOnOff)

            oFileInfo.ReadOnly(VFMXFileInfo::set);

        else

            oFileInfo.ReadOnly(VFMXFileInfo::clear);

       }

   //

   //  force a refresh of the File Manager window.

   //

   Extension()->Refresh();

}

This approach which uses VFMXMenuItem leads to a cleaner solution than the large ugly switch-case statements of Example1


Example1

To try out the example extension, copy EXAMPLE.DLL to your windows directory (C:\WINDOWS) and then add the following to WINFILE.INI.

[AddOns]

EXAMPLE=C:\WINDOWS\EXAMPLE.DLL

Our example class definition looks as follows:

class _export ExampleClass : public VFileManagerExtension

{

   private:

       HMENU hMenu;

   public:

       ExampleClass(void);

       ~ExampleClass(void) {DestroyMenu(hMenu);}

       HMENU    ExtensionMenu(void) {return hMenu;}

       const char *MenuName(void)      {return "Exa&mple";}

       void            InitMenu(HMENU hPopupMenu,int iMenuDelta);

       void            MenuCommand(WORD wItemNumber,BOOL bHelpWanted=FALSE);

       void            SetReadOnly(BOOL bOnOff=TRUE);

};

Note the two inline methods ExtensionMenu() and MenuName().  ExtensionMenu() will return the handle of our extension menu that we will load in the constructor.  MenuName() returns the string that will appear on the File Manager's menu bar for our extension menu.

All extensions must define the body of  AllocateExtension().  This method is called by File Manager++ when the extension DLL is loaded to allocate your derived extension class.

VFileManagerExtension * AllocateExtension(void)

{

   return new ExampleClass();

}

In the body of the constructor for our example class,  we will load a menu resource.  Keep in mind,  that

the items on this menu may only have command values between 1and 99.

ExampleClass::ExampleClass(void) :VFileManagerExtension()

{

   hMenu = LoadMenu(xhLibInstance,MAKEINTRESOURCE(IDM_MENU));

}

In order to process user selections of the items on our extension menu,  we need to define an override

of the MenuCommand() method.  This method is called whenever the user selects an item on our extension menu.

void ExampleClass::MenuCommand(WORD wItemNumber,BOOL /*bHelpWanted*/)

{

   switch (wItemNumber)

          {

           case  CM_READONLY:

                 SetReadOnly();

                 break;

           case  CM_WRITEABLE:

                 SetReadOnly(FALSE);

                 break;

          }

}

Whenever the user selects our extension's popup menu from the File Manager menu bar,

InitMenu() is called to allow our extension a chance to initialize the menu items.  In our override,

we disable the items if no files are selected. Remember that we have to add the specified delta

to our command values to set the menu items correctly.

void ExampleClass::InitMenu(HMENU hPopupMenu,int iMenuDelta)

{

     BOOL bEnableItems = (SelectionCount() > 0);

     WORD wFlags = MF_BYCOMMAND;

     wFlags |=  (bEnableItems) ? MF_ENABLED : MF_GRAYED;

     EnableMenuItem(hPopupMenu,CM_READONLY +iMenuDelta,wFlags);

     EnableMenuItem(hPopupMenu,CM_WRITEABLE+iMenuDelta,wFlags);

}

When our menu items are selected we will call the following method to loop

through the selected files and write-protect or unwrite-protect each of the selected files:

void ExampleClass::SetReadOnly(BOOL bOnOff=TRUE)

{

   int nSelections = SelectionCount();

   for (int iSelection=0;iSelection<nSelections;iSelection++)

       {

        VFMXFileInfo& oFileInfo = FileSelection(iSelection);

        if (bOnOff)

            oFileInfo.ReadOnly(VFMXFileInfo::set);

        else

            oFileInfo.ReadOnly(VFMXFileInfo::clear);

       }

   Refresh();

}

That's all there is to creating a  File Manager extension with FileManager++.  See Example2 for a more object-oriented approach to processing menu items.


CheckMarkDimensions

Method:

CheckMarkDimensions

Class :

VFMXMenuItem

Arguments:

int&   iWidth

int&   iHeight

Description :

This method returns the width (iWidth) and height (iHeight) in pixels required of check mark bitmaps.

See CheckedBitmap() and UncheckedBitmap()

Return:

void